Skip to content

Several files in one annotate review (0.29 PR 4, bundles) - #1718

Merged
backnotprop merged 3 commits into
mainfrom
feat/annotate-bundles
Oct 5, 2026
Merged

backnotprop merged 3 commits into
mainfrom
feat/annotate-bundles

Conversation

@backnotprop

@backnotprop backnotprop commented Oct 5, 2026 •

Copy link
Copy Markdown
Owner

PR 4 of the 0.29 agent-sessions design (.product/drafts/agent-sessions-0.29/DESIGN.md, section A). Several files open as one annotate review, in the order given, with one decision.

What it does

plannotator annotate spec.md ui/mock.html notes.md opens one review when every argument is an existing file named by its path. There is no flag and no file-count limit. The same works from:

  • the plannotator tool, with target: [...]
  • a Bash command the Claude Code mod takes over
  • /plannotator-annotate a.md b.md on Pi, and on OpenCode (embedded and CLI bridge)

In the browser:

  • The first file opens right away.
  • A header switcher ("2 of 3 · mock.html ‹ ›") and the Files tab list the files in the given order. They are never sorted.
  • Each file renders as it does alone: markdown, raw HTML (pinpoint), or diagram files.
  • Send Feedback sends one message with one section per file, in bundle order. With --gate, Approve covers every file.
  • The All files panel follows the bundle order.
  • Ask AI's surface line reads "annotating …/mock.html, file 2 of 3".

Argument rule (shared, packages/shared/annotate-target.ts)

  • One argument: unchanged.
  • Several arguments, all existing files named by path: a bundle. "Named by path" means the path resolves from the cwd, from ~, or with an @ prefix. A name found only by searching the project does not count. Duplicate paths are dropped. An unsupported file type or a file over 2MB fails, and the error names the file.
  • Prose plus exactly one file: unchanged; that file opens.
  • Several targets, but not all of them files named by path (prose around them, a URL, a folder, or a searched name): unchanged ambiguity error, plus one hint line: "To review several files together, pass only their paths: …". Only hosts that can open bundles add the hint.
  • Nothing resolves, or an unknown dash flag: unchanged.
  • Strict gates: several existing files make a bundle. Any other multi-argument call exits 2. Before this change, extra words were silently ignored.

Server (Bun and the Pi mirror)

New mode annotate-bundle, built on folder mode:

  • /api/plan adds bundle: [{ path, renderAs }], and projectRoot is the deepest directory that holds every file.
  • /api/doc uses the single-file rule: the cwd plus each file's own directory. A document a bundle file links to opens as a linked document; anything outside those roots gets 403. The editor never walks the bundle root.
  • Each text file's version history is saved when the review opens.
  • Drafts: the session draft is keyed by the ordered list, and each file's comments are also saved under that file's path key (Annotate drafts follow the file's path (0.29 PR 2) #1710).
  • Host status lists the files. Source save (Edit Mode writes) is off in bundles.
  • The host result record and the feedback archive gain documents: [{ path, annotationCount }]. The archive surface is annotate-bundle.
  • The agent message reads Files: a, b, c on every host.

Contract and mod

  • The tool description gains: "Pass a list as target to review several files together, in the order you want them read."
  • plannotatorToolArgs already passed one argument per file.
  • New contract helpers, synced byte-for-byte into the mod's copy:
    • plannotatorBundleSubject names the bundle ("3 files: spec.md, mock.html, notes.md"). That name appears in the opened text, the list, and the decision heading.
    • isOlderCliBundleRefusal detects an older CLI: its ambiguity error lacks the hint line.
    • looksLikeFilePath reads a word's shape (path separator, leading ~ . @, or a file extension).
  • Bash take-over turns several words into target: [...] only when every word looks like a file path. Prose still runs as written.
  • The mod no longer answers lists with "unavailable". It launches the bundle, and maps an older CLI's refusal to "update Plannotator to open several files at once", for both the tool and the slash command. The OpenCode CLI bridge does the same.

Tests

  • Selection table (annotate-target.test.ts): every rule above, including prose plus one file, prose plus two files, a URL, a folder, and a searched name.
  • Server scenarios on both runtimes (annotate-bundle.scenarios.ts):
    • order and render modes in /api/plan
    • each file served as it renders alone
    • the linked-document rule, and 403 outside the roots
    • per-file history at open
    • one archive record with per-file counts
    • a file's comments following it into a single-file session
    • fewer than two files refused
  • CLI as a process (annotate-bundle-cli.test.ts):
    • order with a duplicate dropped
    • one decision, and the host record's documents
    • a strict bundle approve
    • an unsupported file named in the error
    • a folder among the paths gets the hint
    • strict extra words exit 2
  • Contract: string vs array parse; take-over of several paths vs prose; the older-CLI detection; the hint copy pinned equal to the shared one.
  • Mod: a bundle launch and decision heading; the older-CLI mapping for the tool and the command; the current CLI's error shown as is.
  • OpenCode: the embedded command opens a bundle; the CLI bridge passes one argument per path and maps an older CLI.
  • Unit: shared/annotate-bundle.test.ts, the export order in feedbackDocuments.test.ts, the All files order in annotationScope.test.ts, the Ask surface line in session-bridge.test.ts.
  • DOM (App.bundle.test.tsx, added to the CI DOM list): the first file opens; the switcher and the file list keep the given order; the bundle root is never fetched; Next works; Send Feedback has one section per file in bundle order, each comment once.

Runs:

  • bun test (all): 6345 pass (after the follow-up commit).
  • DOM_TESTS=1 bun test --isolate packages/editor: 281 pass.
  • bun run typecheck: clean.
  • claude plugin validate apps/hook: passes.
  • scripts/test-claude-code-mod.sh could not run here: the local Claude Code has hooks modules turned off by the rollout switch.

Headless Chromium against the built app, running plannotator annotate ui/mock.html notes.md:

  • The switcher showed "1 of 2 · mock.html", and the Files tab listed ui/mock.html, notes.md in that order.
  • One pinpoint comment on the HTML file, Next ("2 of 2 · notes.md"), and one text comment on the markdown file.
  • All files showed mock.html first, then notes.md.
  • Send Feedback printed one "File Feedback" export with a ## …/ui/mock.html section followed by a ## …/notes.md section.

Deviations and notes

  • "An unlisted sibling is refused" is read together with "the single-file rule". An unlisted file is never in the bundle's list, switcher, or host documents. A sibling the files link to still opens as a linked document, exactly as from a single file. Files outside every bundle file's directory are refused. A test pins this behavior.
  • Per-file decisions are not built (the design defers them). Edit Mode writes are off in bundles.
  • WebMCP reports a bundle session as annotate-folder; list_documents lists the bundle files.

backnotprop and others added 3 commits October 5, 2026 11:17
plannotator annotate spec.md mock.html notes.md (every argument an existing
file named by its path) opens ONE review of the files, in the typed order,
with one decision. No flag, no file-count limit.

- Shared rule (annotate-target.ts, vendored to Pi): probeAnnotateBundlePath,
  the bundle selection, resolveAnnotateBundleFiles (type and 2MB checks that
  name the file). Prose, URLs, folders and searched names keep the #1483
  tiers; the ambiguity error gains a hint on hosts that open bundles. Strict
  gates take only a single target or only file paths (else exit 2).
- Server mode annotate-bundle in Bun and Pi: /api/plan carries bundle, /api/doc
  follows the single-file rule per file, history saved per text file at open,
  per-file draft copies (#1710), host status documents, archive surface
  annotate-bundle with target.documents.
- CLI: host result record gains documents; the agent message names every file.
- Editor: first file opens by itself, header switcher (2 of 3 · name), the
  Files tab and All files panel in bundle order, export one section per file in
  bundle order, Ask AI surface line names file N of M.
- Tool contract: description line for lists, plannotatorBundleSubject,
  isOlderCliBundleRefusal; Bash take-over maps several file paths to a list.
  Mod launches bundles and maps an older CLI's refusal to an update message.
- Pi and OpenCode (embedded and CLI bridge) slash commands open bundles too.

Co-Authored-By: Claude <noreply@anthropic.com>
- Move annotate-bundle out of @plannotator/core into packages/shared (no new
  core export, so the published-UI smoke passes without a core publish).
- A list of file paths with a missing file fails naming it (shared 'missing'
  selection) on the CLI, Pi and OpenCode; tool list entries are passed as paths
  (bare word -> ./word) so the tool and Bash take-over get the same rule.
- Strict refusal decided by probe only (no fetch, live probe or Resolved: line).
- A symlinked bundle file is served: its real directory is a root for it.
- The CLI uses the shared selection end to end (a.md ./a.md opens a.md).
- .env named as refused; bundle files have no Close pill and leaving a linked
  document returns to the last bundle file; docs; engine-harness bundle case.

Co-Authored-By: Claude <noreply@anthropic.com>
A stray . or .. (or any existing directory) beside file paths was read as a
missing file ('File not found: .'), where main opened the file. The missing
selection now needs the new pathExists option (annotatePathExists): only a
token with nothing at its path, and nothing found by search, is missing.
Wired on the CLI, Pi and OpenCode; test rows on the shared rule and the CLI.
Symlink-root comment corrected; AGENTS.md notes the dotted-word edge.

Co-Authored-By: Claude <noreply@anthropic.com>
@backnotprop
backnotprop merged commit 88d7b4f into main Oct 5, 2026
64 of 67 checks passed
backnotprop added a commit that referenced this pull request Oct 5, 2026
Brings in #1719 (platform flag), #1717, 0.28.4 and #1718 (bundles).
Resolution keeps both sides:
- Pi review delivery uses classifyReviewOutcome (the server's platform
  flag; nothing inferred from the annotation count) inside the shared
  launchCodeReview, with this branch's decision heading. The platform
  status post is labeled "Posted to the pull request".
- Bundles go through launchAnnotate, shared by /plannotator-annotate and
  the tool. A tool list target opens one annotate-bundle review in order
  (only the shared selection's bundle outcome opens; missing, folder or
  URL entries refuse). Its subject is plannotatorBundleSubject in the
  result, list, close and decision heading.
- Tests: bundle via the tool (order, list, feedback, close), a list that
  would open fewer files refuses, description-only review feedback through
  the tool path, and the platform post delivered verbatim.

Co-Authored-By: Claude <noreply@anthropic.com>
backnotprop added a commit that referenced this pull request Oct 5, 2026
Brings in #1719 (explicit review `platform` flag), #1717, 0.28.4 and #1718
(bundles). Resolutions and follow-ups:
- cli-bridge annotate: bundle framing ("Files: …") and the older-CLI
  several-paths mapping kept, plus the tool's gated bare approval, failure
  reports and the agent-close log.
- The tool opens a list target as one bundle review through the same launch
  (annotateBundle: each file its own CLI argument; a single tool target is
  never re-split); the subject is plannotatorBundleSubject in the result, list
  and decision heading; an older CLI's refusal answers the bundle update text.
  Slash-command bundles get the same subject.
- Review headings use the platform flag (isPlatformPost, isPRMode fallback
  only without the flag): "Review posted" for the status post, "Changes
  requested" for anything else, never inferred from zero annotations.
- opencode-review carries both #1719's platform and the additive
  annotationCount.
- Tests: a bundle via the tool (argv order, name, list, heading, older CLI),
  description-only PR feedback vs a platform post.

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant